chore(agents): harden worktree-first guard + surface Directive #11 via CLAUDE.md#2517
Merged
Conversation
…a CLAUDE.md The guard-main-checkout PreToolUse hook had two holes agents fell through: 1. It checked `branch != main`, so creating a feature branch on the SHARED primary checkout passed the guard while the tree could still be switched/reset under you. It now checks "is the edited file in a linked worktree" — a branch on the primary checkout is blocked. Enforces the directive's intent, not a proxy. 2. It only inspected $CLAUDE_PROJECT_DIR, so editing a sibling repo (objectui / cloud) on its shared checkout from this session was silently unguarded. It now parses the edited file's path and checks THAT repo's checkout — cross-repo safe. Also: - Add CLAUDE.md (auto-loaded into agent context, unlike AGENTS.md) that inlines the worktree-first rule + the command and points to AGENTS.md for the full playbook. The prior gap: AGENTS.md #11 was clear but never reached the agent's context. - Update AGENTS.md #11 to describe the hardened hook behaviour. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
added a commit
that referenced
this pull request
Jul 2, 2026
…fail-open) (#2519) Follow-up to #2517. The guard ran `git -C "$(dirname file)"`, which fails when the edited file's parent directory doesn't exist yet (a Write creating a new nested dir) — and `|| exit 0` then let the edit through on the shared checkout. Now it walks up to the nearest existing ancestor before resolving the repo, so new-file-in-new-dir writes are guarded too. (Also applied to objectui#2160 / cloud#721.) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Prime Directive #11 (worktree-first) is well written in AGENTS.md, yet agents (this one included) still edited on shared checkouts. Root cause wasn't the prose — it was enforcement + reach:
guard-main-checkout.shblocked only whenbranch == main. Creating a feature branch on the shared primary checkout passed the guard while the tree could still be switched/reset under you — the exact loophole that got hit (feat/studio-*on the shared objectui checkout;wip/session-off-mainon framework).$CLAUDE_PROJECT_DIR, so editing a sibling repo (objectui/cloud) on its shared checkout from a framework session was silently unguarded.CLAUDE.md(which is auto-loaded); AGENTS.md isn't. So the agent started blind to Migrate documentation site to Fumadocs with monorepo structure and shared content #11 and only learned it when the guard fired — where loophole Add metamodel interfaces for ObjectQL/ObjectUI contract #1 let it be bypassed.What
git rev-parse --git-dirunder.git/worktrees/…), notbranch != main. A branch on the shared checkout is blocked.tool_input.file_pathfrom the PreToolUse stdin), so sibling repos are covered too — not just$CLAUDE_PROJECT_DIR.CLAUDE.md(auto-loaded): inlines the worktree-first rule + command, extends it to sibling repos, and points to AGENTS.md for the full playbook. (Inlining the critical rule beats a bare "go read AGENTS.md" — same weak indirection that failed.)Verified (hook unit tests)
OS_ALLOW_MAIN_EDITS=1Authored from a worktree (
framework-guardfix), per #11.🤖 Generated with Claude Code